Node / meshtastic / Meshtastic-Android / files / .github / copilot-instructions.md

Displaying Rendered • View raw • Download

Meshtastic-Android is a native Android client application for the Meshtastic mesh networking project. It enables users to communicate via off-grid, decentralized mesh networks using LoRa radios. The app is written in Kotlin and follows modern Android development practices.

• Language: Kotlin (primary), with some Java and AIDL files

• Build System: Gradle with Kotlin DSL

• Size: ~3MB source code across 3 modules

• Target Platform: Android API 26+ (Android 8.0+), targeting API 36

• Architecture: Modern Android with Jetpack Compose, Hilt DI, Room database

• Product Flavors: T383838fdroid (F-Droid) and T383838google (Google Play Store)

• Build Types: T383838debug and T383838release

1. JDK Requirement: JDK 21 is required (will fail with other versions)

2. Secrets Configuration: Copy T383838secrets.defaults.properties to T383838local.properties and update:

T282828

Te6edf3MAPS_API_KEYTff7b72=Ta5d6ffyour_google_maps_api_key_here

Te6edf3datadogApplicationIdTff7b72=Ta5d6ffyour_datadog_app_id

Te6edf3datadogClientTokenTff7b72=Ta5d6ffyour_datadog_client_token

3. Clean Environment: Always start with T383838./gradlew clean for fresh builds

T282828

./gradlew clean

T8b949e# 2. Check code formatting (run before making changes)

./gradlew spotlessCheck

T8b949e# 3. Apply automatic code formatting fixes

./gradlew spotlessApply

T8b949e# 4. Run static code analysis/linting

./gradlew detekt

T8b949e# 5. Build debug APKs for both flavors (takes 3-5 minutes)

./gradlew assembleDebug

T8b949e# 6. Build specific flavor variants

./gradlew assembleFdroidDebug T8b949e# F-Droid debug build

./gradlew assembleGoogleDebug T8b949e# Google debug build

./gradlew assembleFdroidRelease T8b949e# F-Droid release build

./gradlew assembleGoogleRelease T8b949e# Google release build

T8b949e# 7. Run local unit tests (takes 2-3 minutes)

./gradlew Tffa657test

T8b949e# 8. Run specific flavor unit tests

./gradlew testFdroidDebug

./gradlew testGoogleDebug

T8b949e# 9. Run instrumented tests (requires Android device/emulator, takes 5-10 minutes)

./gradlew connectedAndroidTest

T8b949e# 10. Run lint checks for both flavors

./gradlew lintFdroidDebug lintGoogleDebug

• Clean build: 3-5 minutes

• Unit tests: 2-3 minutes

• Instrumented tests: 5-10 minutes

• Detekt analysis: 1-2 minutes

• Spotless formatting: 30 seconds

• Android SDK API 36 (compile target)

• JDK 21 (NOT JDK 17 or 11 - build will fail)

• Gradle 9.0+ (downloaded automatically by wrapper)

• Install pre-push Git hook: T383838./gradlew spotlessInstallGitPrePushHook --no-configuration-cache

T282828

• T383838buildSrc/src/main/kotlin/Configs.kt - Version constants and build config

• T383838app/build.gradle.kts - Main app build configuration

• T383838config/detekt/detekt.yml - Static analysis rules

• T383838config/spotless/.editorconfig - Code formatting rules

• T383838gradle.properties - Gradle build settings

• T383838secrets.defaults.properties - Template for secrets (copy to T383838local.properties)

• UI Framework: Jetpack Compose with Material 3

• State Management: Unidirectional Data Flow with ViewModels

• Dependency Injection: Hilt

• Navigation: Jetpack Navigation Compose

• Local Data: Room database + DataStore preferences

• Remote Data: Custom Bluetooth/WiFi protocol + HTTP API (network module)

• Background Work: WorkManager

• Communication: AIDL service interface (T383838IMeshService.aidl)

• pull-request.yml - Runs on every PR: build, detekt, tests

• reusable-android-build.yml - Shared build logic: spotless, detekt, lint, assemble, test

• reusable-android-test.yml - Instrumented tests on Android emulators (API 26, 35)

T282828

./gradlew :app:spotlessCheck :app:detekt :app:lintFdroidDebug :app:lintGoogleDebug :app:assembleDebug :app:testFdroidDebug :app:testGoogleDebug --configuration-cache --scan

./gradlew :app:connectedFdroidDebugAndroidTest :app:connectedGoogleDebugAndroidTest --configuration-cache --scan

1. Code Style: Spotless check (auto-fixable with T383838spotlessApply)

2. Static Analysis: Detekt with custom rules in T383838config/detekt/detekt.yml

3. Lint Checks: Android lint for both flavors

4. Unit Tests: JUnit tests in T383838app/src/test/

5. UI Tests: Compose UI tests in T383838app/src/androidTest/

• Gradle version error: Ensure JDK 21 (NOT 17 or 11)

• Missing secrets: Copy T383838secrets.defaults.properties → T383838local.properties

• Configuration cache: Add T383838--no-configuration-cache flag if issues persist

• Clean state: Always run T383838./gradlew clean before debugging build issues

• Instrumented tests: Require Android device/emulator with API 26+

• UI tests: Use T383838ComposeTestRule for Compose UI testing

• Coroutine tests: Use T383838kotlinx.coroutines.test library

• Formatting: Run T383838./gradlew spotlessApply to auto-fix

• Detekt warnings: Check T383838config/detekt/detekt.yml for rules

• Localization: Use T383838stringResource(R.string.key) instead of hardcoded strings

• Main Activity: T383838app/src/main/java/com/geeksville/mesh/ui/MainActivity.kt

• Service Interface: T383838app/src/main/aidl/com/geeksville/mesh/IMeshService.aidl

• UI Screens: T383838app/src/main/java/com/geeksville/mesh/ui/

• Data Layer: T383838app/src/main/java/com/geeksville/mesh/repository/

• Database: T383838app/src/main/java/com/geeksville/mesh/database/

• Models: T383838app/src/main/java/com/geeksville/mesh/model/

• Non-obvious deps: Protobuf for device communication, DataDog for analytics (Google flavor)

• Flavor-specific: Google Services (google flavor), no analytics (fdroid flavor)

• Version catalog: Dependencies defined in T383838gradle/libs.versions.toml

TRUST THESE INSTRUCTIONS - they are validated and comprehensive. Only search for additional information if:

1. Commands fail with unexpected errors

2. Information appears outdated

3. Working on areas not covered above

Always prefer: Using the documented commands over exploring alternatives, as they are tested and proven to work in the CI environment.

For code changes: Follow the architecture patterns established in existing code, maintain the modular structure, and ensure all validation steps pass before submitting changes.